library object
This method will call a specified function from within the associated DLL library, returning a handle to a dictionary containing the results of the call.
dictionary@ call(string function_signature, ? list_of_parameters)
Parameters:
function_signature
The function signature expected by the library.
list_of_parameters
The list of parameters expected by the specified function signature.
Return value:
A handle to a dictionary containing the results of the call. If the call failed, the dictionary will be empty (see remarks).
Remarks:
Similarly to calling functions in BGT, the list of parameters are passed according to the function signature provided in the first parameter, and are separated by commas.
If the call was successful, the function will return a handle to a dictionary containing all the results of the call. Since some parameters may actually be modified by the library, I.E. if they are passed as pointers (see below), the dictionary will provide the return value as key 0, and the parameters we passed to the DLL as the number of the parameter (see the example for how this works in practice).
At present, it is only possible to call DLL's that export a C style interface either using stdcall or cdecl, which the absolute majority of them do. All the Windows API DLL's, for instance, use stdcall and export C interfaces.
The function signature you provide should match that stored in the library for it to succeed.
Below is a list of datatypes that the function signature can currently process.
- char*: Equivalent to a BGT string. Internally, this is a pointer to an array of characters (see below).
- char: The same as int8 in BGT.
- unsigned char: The same as uint8 in BGT.
- short, int, long: The same as in BGT.
- unsigned short, unsigned int, unsigned long: The same as ushort, uint and ulong in BGT.
- BOOL: This is a Windows datatype that is the same size as a long.
- Handles: The Windows API has several different handle datatypes. These can all be processed as an int, as they are pointers. If a handle needs to be passed as null, the null keyword can be used in the same way as in BGT.
Sometimes, DLL's may expect and/or return what are called pointers. Put simply, a pointer is a special type of variable in C which provides the location in memory of a particular piece of data. If you are familiar with object handles in BGT, then you can apply a similar concept to pointers in C. If a function expects a pointer, then you give it the variable type, followed by a star sign (*). For example, to pass a pointer to an int you would use int*. To pass a string, you would use char*, since a string is a pointer to an array of characters.
if a parameter you are passing is smaller than the type that the function expects based on the signature string, it will be converted if possible. For instance, let's say the function takes an int and you pass a short from the script, it will automatically be converted to an int internally before it is passed. However, implicit type conversions are only attempted if the parameter in question is not a pointer.
Theoretically, function signatures can contain parameters with multiple pointers, such as int**, int*** etc. At present, only one level of indirection is supported. This means that only one pointer, such as int*, can be used for any one parameter.
If for some reason the call fails the parsing sequence, a runtime error will be triggered.
Example:
// Retrieve the computer name and display it in a message box, all with DLL's.
// Define the information constant.
const int win32_mb_icon_information=0x00000040;
void main()
{
// Declare some variables.
library dll; // This will do all the nifty work.
dictionary@ dll_result; // This will contain the result of the call.
string name; // This will hold our computer name.
/*
Since the DLL expects us to allocate our own memory for the string, we will resize the string to a decent length so that the DLL can fill it.
*/
name.resize(500);
// Load the library.
dll.load("kernel32.dll");
// Call the function that will retrieve our computer name. It takes the string that is to hold the computer name, and its length.
@dll_result=dll.call("int GetComputerNameA(char*, int*);", name, name.length());
// Unload the library.
dll.unload();
// Retrieve the modified computer name. Since the string that we passed was the first parameter, we retrieve this with key 1.
dll_result.get("1", name);
// Remove the remaining null characters.
name=string_replace(name, "\0", "", true);
// Now we create a message box with the information.
// Load the library containing the MessageBox function.
dll.load("user32.dll");
// Call the MessageBox function.
dll.call("int MessageBoxA(int, char*, char*, int);", 0, "The name assigned to this computer is "+name+".", "Information", win32_mb_icon_information);
}